using System.Collections.Generic;

namespace System.Caching
{
    /// <summary>
    /// Key-based Cache.
    /// </summary>
    /// <typeparam name="TKey">Key <see cref="Type">type</see>.</typeparam>
    /// <typeparam name="TValue">Value <see cref="Type">type</see>.</typeparam>
    public interface ICache<TKey, TValue>
    {
        /// <summary>
        /// When implemented returns <see cref="IEnumerable{T}">enumeration</see> of all cached items as <see cref="KeyValuePair{TKey,TValue}">pairs of key and value</see>.
        /// </summary>
        /// <returns>
        /// <see cref="IEnumerable{T}">Enumeration</see> of all cached items as <see cref="KeyValuePair{TKey,TValue}">pairs of key and value</see>.
        /// </returns>
        IEnumerable<KeyValuePair<TKey, TValue>> GetAll();

        /// <summary>
        /// When implemented initializes cache with predefined set of <see cref="KeyValuePair{TKey,TValue}">key-value pairs</see>.
        /// </summary>
        /// <param name="items">
        /// <see cref="IEnumerable{T}">Enumeration</see> of all items as <see cref="KeyValuePair{TKey,TValue}">pairs of key and value</see>.
        /// </param>
        void Initialize(IEnumerable<KeyValuePair<TKey, TValue>> items);

        /// <summary>
        /// When implemented determines whether cache contains key.
        /// </summary>
        /// <param name="key">key.</param>
        /// <returns>True or false.</returns>
        bool Contains(TKey key);

        /// <summary>
        /// When implemented tries to get value by key.
        /// </summary>
        /// <param name="key">Key.</param>
        /// <param name="value">Value parameter to be filled.</param>
        /// <returns>True if success, otherwise false.</returns>
        bool TryGet(TKey key, out TValue value);

        /// <summary>
        /// When implemented tries to put key-value pair into cache.
        /// </summary>
        /// <param name="key">Key.</param>
        /// <param name="value">Value.</param>
        /// <returns>True if success, otherwise false.</returns>
        bool TryPut(TKey key, TValue value);
        
        /// <summary>
        /// When implemented removes all items.
        /// </summary>
        void Clear();
    }
}